Under normal conditions, TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr and
TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa will return an identifier for the
requested cursor. If an error occurs in creating the
cursor, such as when _n_a_m_e_I_d refers to a non-existent file,
then NNNNoooonnnneeee is returned and an error message will be stored in
_i_n_t_e_r_p->_r_e_s_u_l_t.
TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr and TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa maintain a database of
all the cursors they have created. Whenever possible, a
call to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr or TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa will return an
existing cursor rather than creating a new one. This
approach can substantially reduce server overhead, so the Tk
procedures should generally be used in preference to Xlib
procedures like XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttCCCCuuuurrrrssssoooorrrr or XXXXCCCCrrrreeeeaaaatttteeeePPPPiiiixxxxmmmmaaaappppCCCCuuuurrrrssssoooorrrr,
which create a new cursor on each call.
The procedure TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCuuuurrrrssssoooorrrr is roughly the inverse of
TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr. If its _c_u_r_s_o_r argument was created by
TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr, then the return value is the _n_a_m_e_I_d argument
that was passed to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr to create the cursor. If
_c_u_r_s_o_r was created by a call to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa, or by
any other mechanism, then the return value is a hexadecimal
string giving the X identifier for the cursor. Note: the
string returned by TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCuuuurrrrssssoooorrrr is only guaranteed to
persist until the next call to TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCuuuurrrrssssoooorrrr.
When a cursor returned by TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr or
TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa is no longer needed, TTTTkkkk____FFFFrrrreeeeeeeeCCCCuuuurrrrssssoooorrrr
should be called to release it. There should be exactly one
call to TTTTkkkk____FFFFrrrreeeeeeeeCCCCuuuurrrrssssoooorrrr for each call to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr or
TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa. When a cursor is no longer in use
anywhere (i.e. it has been freed as many times as it has
been gotten) TTTTkkkk____FFFFrrrreeeeeeeeCCCCuuuurrrrssssoooorrrr will release it to the X server
and remove it from the database.
BBBBUUUUGGGGSSSS
In determining whether an existing cursor can be used to
satisfy a new request, TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr and TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa
consider only the immediate values of their arguments. For
example, when a file name is passed to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr,
TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr will assume it is safe to re-use an existing
cursor created from the same file name: it will not check
to see whether the file itself has changed, or whether the
current directory has changed, thereby causing the name to
refer to a different file. Similarly, TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa
assumes that if the same _s_o_u_r_c_e pointer is used in two
different calls, then the pointers refer to the same data;
it does not check to see if the actual data values have
